// SAX locator interface for document events.
// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
// $Id: Locator.java,v 1.8 2002/01/30 21:13:47 dbrownell Exp $

package org.xml.sax;


/**
 * 定位器：
 *
 * SAX解析定位接口，通过行和列进行定位，将SAX事件与文档位置相关联
 *
 * 在SAX解析器中调用{@link org.xml.sax.ContentHandler#setDocumentLocator setDocumentLocator}来绑定该接口的实例，
 * 然后解析器就可以通过这个对象来获取其他SAX事件的位置。
 * 请注意，该接口的实例对象返回的结果仅在每个回调方法的范围内有效，如果在任何其他时间尝试使用定位器，
 * 或者在解析完成后，应用程序将收到不可预知的结果。
 *
 * SAX解析器对locator实例对象不是必须的，但是最好绑定一下，并且应该在其它任何事件reporting之前设置，
 * 如果SAX解析器接受到{@link org.xml.sax.ContentHandler#startDocument startDocument}事件，但此时还没有设置locator实例对象，
 * 应用程序就会默认定位器不可用
 *
 * @version 2.0.1 (sax2r2)
 * @see org.xml.sax.ContentHandler#setDocumentLocator
 */
public interface Locator {


    /**
     * 返回当前文档事件的公共标识符。
     * 返回值是文档实体或触发事件标记的外部解析实体的公共标识符。
     * @return 包含公共标识符的字符串;如果没有可用的字符串，则为null。
     * @see #getSystemId
     */
    public abstract String getPublicId ();


    /**
     * 返回当前文档事件的系统标识符。
     *返回值是触发事件的标记出现的文档实体或外部解析实体的系统标识符。
     *如果系统标识符是一个URL，则解析器必须在将其传递给应用程序之前将其完全解析。
     *例如，文件名必须始终作为 file：... URL提供，而其他类型的相对URI也将根据其基础进行解析。
     * @return 包含系统标识符的字符串;如果没有可用的字符串，则返回null
     * @see #getPublicId
     */
    public abstract String getSystemId ();


    /**
     * 返回当前文档事件结束的行号。
     * 行由行结束符定义，在XML规范中定义。
     * 该方法的返回值仅用于诊断的近似值.
     * 它不打算提供足够的信息来编辑原始XML文档的字符内容。
     *在某些情况下，这些“行”号码与显示为列的内容相匹配，而在其他情况下，由于内部实体扩展，这些号码可能与源文本不匹配
     *返回值是触发事件的标记出现的文档实体或外部解析实体的行号的近似值。
     *如果可能，SAX驱动程序应在与文档事件关联的文本之后提供第一个字符的行位置。
     *
     * 行数是从1开始的，不是从0开始
     * @return 行号，如果没有可用，则为-1
     * @see #getColumnNumber
     */
    public abstract int getLineNumber ();


    /**
     * 返回当前文档事件结束的列号。
     * 这是自上一行结束以来基于一个Java char值的数字
     *该方法的返回值仅用于诊断的近似值.
     * 它不打算提供足够的信息来编辑原始XML文档的字符内容。
     *例如，当行包含组合字符序列，宽字符，代理对或双向文本时，该值可能不对应于文本编辑器显示中的列、
     *返回值是触发事件的标记出现的文档实体或外部解析实体的行号的近似值。
     *如果可能，SAX驱动程序应在与文档事件关联的文本之后提供第一个字符的行位置。
     * 行数是从1开始的，不是从0开始
     *
     * @return 列号，如果没有可用的，则为-1
     * @see #getLineNumber
     */
    public abstract int getColumnNumber ();

}
